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Technical Note: 


Functionality of the Terminal 
Handler (TIH), Rel. 1.1 


Terminal handlers (TIHs) are processes which function as the AOL host 
interface to the public data networks and transmit a client’s requests to 
AOL’s backend servers during an online session. 


Introduction 


The TIH is the process. Historically, many TIH processes were run on one 
machine, called the FEP (frontend processor) or TFEP (Terminal Frontend 
Processor). Hence, the term TFEP is often used as a synonym for the TIH, 
which is not accurate. 


With the rollout of the 6.0 client, the production pod architecture was 
changed such that the TIH process now runs on the same machine as its 
BERP (Back-end Routing Process) process. There is one TIH process for 
each machine; there are no longer any TFEP machines. 


From the standpoint of the client, TIH is the entry point to the entire AOL 
infrastructure, while from the standpoint of the host infrastructure, TIH is 
effectively a slave or satellite of the BERP (Back-end Routing Processor). 


In other words, for client developers TIH appears to be everything, while 
for host developers TIH is mostly transparent except to send stats for an 
update Queue Context (QC) message. 


The back-end routing processor (BERP) is a podded UNIX-based server 
that runs a BERP process to routes the client and host messages to the 
appropriate host server. A BERP functions as a controller and network 
router for TIH (terminal handler) messages in a distributed network 
architecture. The BERP writes information to the system log file when 
system problems occur or when the TIH crashes. For more information on 
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BERP, see the Functionality of the BERP Routing Server technical note 
reference in Additional Information on page 2. 





TIH provides the following three main functions: 


¢ Allocates QIDs (queue identifiers), the unique IDs for all host sessions; 
QIDs are the numeric identification for a process and its queue. This 
number is used in the host software to identify the source and 
destination processes for a process message and to identify a member's 
online session. 


e Creates and maintains a user’s Queue Context (QC) 
e Accumulates and writes session statistics for members 


In the case of so-called one-step clients which never connect directly to the 
TIH, TIH does not play a terminal handler role at all but instead provides 
an auxiliary function for the BERP of merely allocating a QID and QC. 


From the standpoint of TIH, one-step and two-step clients are more 
accurately termed connection-less clients and clients with a persistent TIH 
connection. For detailed information on one-step and two-step client 
connectivity, see Additional Information on page 2. 





Who Should Use This Technical Note 


This document is intended for internal America Online employees in Host 
and Client Development, Quality Assurance (QA), and Operations who 
need to understand the functionality of the TTH. 


Additional Information 


For more information on the following topics, see the references cited: 


¢ Login, see the Overview of the Host Login (Sign-on) Subsystem and the 
Overview of Two-Step Login Connectivity and technical notes at the 
sdtechdocs web site at Keyword: techdocs or https:// 
sdtechdocs.web.aol.com 
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BERP, see the Functionality of the BERP Routing Server technical note 
at the sdtechdocs web site at Keyword: techdocs or https:// 
sdtechdocs.web.aol.com 





Queue Context, see the Queue Context Reference at the sdtechdocs web 
site at Keyword: techdocs or https://sdtechdocs.web.aol.com 





IPT, see the Overview of the IP Tunnel Process technical note at the 
sdtechdocs web site at Keyword: techdocs or https:// 
sdtechdocs.web.aol.com 





SecurID, see the Overview of the SecurID Server technical note at the 
sdtechdocs web site at Keyword: techdocs or https:// 
sdtechdocs.web.aol.com 





Comm online processes such as berp, dns_agent, ip_tunnel, net_mux, 
rejector, switchboard, TIH, and TIH_monitor, see the Host Online 
Processes manual at the sdtechdocs web site at Keyword: techdocs or 
https://sdtechdocs.web.aol.com 





SAPI, queue message network, the basic operation of a server 
application, TCL, server API components, and associated functions, 
see The Server API (SAPI) manual at the sdtechdocs web site at 
Keyword: techdocs or https://sdtechdocs.web.aol.com. 
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Terms, Processes, and Components 


Figure | describes the interactions of the TIH: 
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Figure 1: — Interactions of the TIH 
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The BERP terms and interactions are described as follows: 


BERP (back-end 
routing processor) 


IPT (IP Tunnel) 


Login 
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A BERP is a UNIX-based server running the berp 
process which routes client messages to the 
appropriate host process. BERP is the heart of the 
distributed network, interfacing the TIHs on the 
Ethernet to the ring where various servers are 
connected. BERP hosts the session logon time 
and logout time setup. The berp process functions 
as a controller and network router for TIH 
(terminal handler) messages in a distributed 
network architecture. They ensure easy 
monitoring of TIHs and write information to the 
system log file when system problems occur or 
when the TIH crashes. All UNIX host online 
processes incorporate the server API (SAPI) suite 
of TCL commands in their source code. 


A process that acts as a network gateway for 
Internet protocol (IP) packets sent between the 
Internet and America Online clients. The IP 
tunnel process is a host-side process that manages 
a pool of IP addresses, enforces parental controls, 
and routes client IP packets to the Internet (and 
back to the client) through the appropriate 
proprietary protocol. It is the last piece of AOL 
proprietary code an IP packet encounters before it 
is sent to the Internet. When a client connects to 
the America Online service, the IPT process 
assigns: client IP (DAHA) addresses, client 
routes, and client domain name servers. The IPT 
process also filters packets to prevent network 
communication between specific IP addresses and 
America Online members. 


The login subsystem implements and controls the 
user interface responding to members who are 
signing on or off the online service. Login 
monitors member connection time and login 
activity and updates the master account database 
with current usage data. This data is used for both 
billing members and managing the host network 
operations. The subsystem also updates the client 
software and makes promotional forms and 
features available through Welcome forms. 
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OSCAR (Open System 
for Communication 
Access in Realtime) 


Pod 


PLOT (Proxy Logon 
Thingee) 


POG (podded OSCAR 
gateway) 


P3 (Playnet Proprietary 
Protocol) 


Public Data Network 


© America Online, Inc. 2001 


An implementation of bucky technology that 
supports AOL Instant Messenger, Buddy Lists, 
and Locate. OSCAR server processes are called 
bucky balls, because they were represented by 
round shapes in early design diagrams. 


A set of UNIX-based servers on an IP subnet that 
supports 40,000 simultaneous users signed on to 
the service. Pods are added to the host system as 
the number of simultaneous online members 
increases. Pods allow AOL staff to avoid taking 
the entire service down to perform maintenance 
and upgrades. 


PLOT authenticates and sends a message to 
BERP to reserve a QID from TIH. TIH then 
reserves a QID and returns <<OK>> to the IPT 
through BERP and PLOT. 


NOTE: PLOT’s login function is moving to the 
BERP, so IPT will directly communicate with 
BERP. After the redesign, however, PLOT still 
will handle the BOS (basic OSCAR services) 
reservation. 


A server that contains the podded OSCAR 
gateway (POG) interface between OSCAR 
processes and the pod. 


A protocol for connecting computers to the 
Internet through dialup telephone connections 
incorporating superior data negotiation, 
compression, and error correction than Serial Line 
Internet Protocol (SLIP). 


A network that includes phone lines, point of 
presence (POP) modems, and packet switching 
networks using a transmission control protocol 
(TCP). 
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SNAC (Simple 
Network Atomic 
Communication) 


TIH (terminal handler) 


SNAC messages are application-level 
communication units which the infrastructure 
uses for authentication during login between 
OSCAR clients such as AOL TV and AIM clients 
and servers. A SNAC consists of a header 
followed by a data portion. The layout of the 
SNAC header is pre-defined and handled 
automatically. The layout of the SNAC data 
portion is as prescribed in its definition. 


A TIH is part of the is the host process that acts as 
the interface between the public data networks 
and the AOL host infrastructure. TIH controls the 
communications connection between the client 
and the host system. It also provides a message 
routing function and accumulates session 
statistics for members. There are two existing TIH 
processes: x25_TIH and sst_TIH. 


Protocols and Process Types 


There are two existing TIH processes: 


X25_TIH 


SST_TIH 


supports connections with the X.25 


supports connections with all other clients 


The primary purpose of TIH is to maintain the connection to the user. 


The token message architecture is summarized in Figure 2: 








token messages 














Figure 2: Token Message Architecture 


America Online Confidential 


7 © America Online, Inc. 2001 





July 2001 


Technical Note: Functionality of the Terminal Handler (TIH), Rel. 1.1 


FLAP (Frame Layer Protocol) is only for clients using TCP connections, 
while P3 (Point-to-point Protocol) is used either for TCP (Transmission 
Control Protocol) or X25 connections. 


The token is two bytes which tell the BERP which host server to route the 
message to. For example, the Dd token routes message to the login server. 
TIH and BERP each have token tables. 


Traditional clients use FDO (Forms Display Operation) language in the 
token messages. Newer devices use SNAC (Simple Network Atomic 
Communication). 


For more detailed information on FLAP, P3, and token messages, see 
Connection Overview. 





Connection Overview 


TIH is the server that clients actually connect to. All other host servers hide 
behind TIH. For example, when client connects to AmericaOnline.aol.com, 
the DNS rotor resolves it to one of the TIHs. 


TIH forwards the token messages to BERP and the messages are forwarded 
to other servers in our host complex using QMI. 


TIH is not on the QMI network. It relies on a TCP connection to the BERP 
over which a private protocol is used to exchange messages between the it 
and the BERP. 


All QMI messages between TIH and other servers are tunneled through 
this link. 


With older clients, 4.0 or earlier, TIH is the only connection and every 
packet goes through TIH. TCP/IP traffic is tunneled through TIH using yc/ 
yd tokens. With 5.0 clients, TCP/IP does not go through TIH anymore and 
itis routed by SuperTunnel. With 6.0, a new connection to BOSS is created 
to handle buddy lists and IMs. 


NOTE: Even though client may have several connections to host, the one 
to TIH is very special. Whenever this connection is terminated, TIH sends 
out UNPLUGs to other servers. If a client, for example, uses TIH only for 
Login, make sure to end the session if the TIH connection is down. 
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P3 


FLAP 


Most clients use P3 to talk with TIH. P3 is a packet level protocol which is 
built on the top of the calling level or network level protocol, for example, 
X.25 or TCP/IP, and below the application level protocol, suchas ATOM 
protocols. It detects and traps the errors in the exchanging packet. It 
requires that the packet length be in the range of MIN_PACKET_SIZE(Q 
bytes) through MAX_ PACKET. SIZE(128 bytes), that the packet be in the 
correct delivery order, and that the message type is specified. When any 
packet is received, the client and the host system both need to analyze and 
respond to the packet based on P3 protocol requirements. The 
implementation on both the client side and the host side are conceptually 
the same, but since they are developed on different systems and interface 
with different software packages, there are some differences. 


With K2, TIH started to support FLAP. FLAP is a simple frame based 
transport protocol on top of any reliable connection (like TCP). 


A FLAP packet has a 6-byte header, with the following layout: 


ei 1 byte 
Type 1 byte 
Seq_No 2 bytes 
Data_Len 2 bytes 


FLAP is widely used in AIM related projects. 


Token Messages 


The communication between client and TIH uses another protocol called 
Token Messages. In each data frame, the first 2 bytes is considered to be a 
token. TIH routes the message according to a token table. Client also uses 
tokens to dispatch the message to proper modules. 


In most cases, token messages are symmetrical (in that they mean the same 
thing host or client bound). 


Currently, only printable characters are used in tokens. 
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Some common tokens are: 


00 INIT packet 

Ol INFO packet, extension to INIT 

Dd Clear text login token 

Wh Exchange encryption keys with sec_login 

Wd Encrypted data for decrypting by sec_login 

SX SNAC messages to be routed based on foodgroup 

XS/Xs Tell clients to disconnect (client-bound only) 

fP Client-bound ping 

FP Host-bound ping 

LO Client send this message to indicate a normal 
logoff 

SC Inform host sign-on complete 

SD Speed detect 

AT Atom streams (including variations like At, aT, 
at) 


NOTE: In FLAP, there is no special INIT packet so we use 00 token to send 
it as a normal data frame. 


INIT Packet 


For SNAC-based clients during P3 handshaking, there is a special packet 
called the INIT packet. Besides connection-related information, INIT also 
contains everything TIH needs to know about the client and its operating 
environment. 


TIH does not consider the connection fully established until it gets a valid 
INIT. Without INIT, the connection is dropped in 1 minute. 

For example, the INIT packet structure from K2 code is as follows: 

#define INITPACKET_VERSION 1 


typedef struct tagINITPACKET 
{ 
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WORD winitPacketVersion; /* 00-01 Version of the Init Packet %/, 
WORD wExtraPacketCount; /* 02-03 This is the number of 01 tokens the client will send. */ 
WORD wBuildOSFamily; —/* 04-05 OS Type the client was build for */ 


WORD wMajorVersion; /* 06-07 Major client version */ 

WORD wMinorVersion; /* 08-09 Minor client version */ 

WORD wServiceType; /* 10-11 Service Type enum */. 

LONG JUDOTimestamp; /* 12-15 Last UDO timestamp */ 

BYTE _ bDistChannel; /* 16 Distribution channel enum (CD, 
download, etc) e/ 


BYTE _ bBuildVersion; /* 17 Spin letter not used by the host */ 
WORD wBuildCPUType; /* 18-19 CPU for which the client 


was built */ 
WORD wClientOptions; /* 20-21 Misc client options bitmask */ 
WORD wRunOsType; /* 22-23 Running OS Type af 
WORD wCountryCode; /* 24-25 Country Code */ 
WORD wOEM; /* 26-27 OEM enum */ 
DWORD _ dwSessionFlags; /* 28-31 Session Flags */ 
DWORD dwRunOSVersion;  /* 32-35 Running OS Version */ 
LONG 1!ConnectSpeed; /* 36-39 Connection baud rate */ 
BYTE  bLanguage[8]; /* 40-47 Language preferences */ 
DWORD dwServerlIpAddr; /* 48-51 Server IP addr (network 

byte order) */ 
DWORD_ dwLocallpAddr; /* 52-55 Client IP addr a | 
WORD wBuildOSVersion; /* 56-57 Build OS Version */ 
WORD wRunCPUType; /* 58-59 CPU on which the client is 

running e 
char szPhoneNumber[16]; /* 60-75 phone number dialed (NULL padded)*/ 
char szExpansionSpace[8]; /* 76-83 Expansion Space | 
char szTrademark[32]; | /* 84-115 Trademark string id 


} New_INIT_Packet_Definition; 

At minimum, a client must provide the following information: 

wInitPacketVersion : 1 

wExtraPacketCount : 0 (This is to send extra TLVs with 01, most clients 
don’t need this yet). 

Those fields are the version keys and CM assigns them to each new client, 

wBuildOSFamily 

wBuildOSVersion 

wMajorVersion 

wMinorVersion 

wBuildCPUType 

wServiceType 


wCountryCode 


dwServerIpAddr : We need to put some sensible IP address here. This is what we use to calculate the 
network_index. 


Every field needs to be in network byte order (big_endian). 


TIH Events 


The main TIH events include the following functions: 
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e Signing On on page 12 
e Disconnecting on page 12 


e Maintaining a Heartbeat on page 13 





e Updating QC on page 13 


e Sending Stats Record with TIH on page 14 





¢ Kicking User Off with XS Token on page 14 





Once the host receives the INIT packet, the client can initiate the login 
process by sending the user's screenname and password to the Login server 
through tokens. Old clients send the information in clear text with the Dd 
token. Newer clients support secure login. The Wh token is used to 
exchange keys and the Wd token sends the encrypted user screenname and 
password to sec_login which eventually is sent to Login in clear text. 


The detailed Login event flow is described in Detailed Event Flow of 
Member Login on page 15. For more information, see Additional 
Information on page 2 for a reference to the Host Login technical note. 








Once the connection is established, TIH may instruct the client that it can 
start speed detection. If the client supports this feature, it will request data 
from host. After the client receives all the data, it calculates the equivalent 
baudrate and sends it back to TIH. 


Both TIH and client use the SD token to send speed detect related packet. 
Speed detection happens as soon as the connection is established regardless 


of Login process, so it is possible that all servers in the login loop (Login, 
Welcome, Popup) do not have the detected speed in QC. 


Disconnecting 


The typical disconnect sequence is as follows: 
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1. To sign off normally, send LO token to host and immediately drop the 
the connection by sending SIGNOFF frame. 


2. If you get XS/Xs token, display the message and drop the connection. 
3. If connection is dropped without XS token, this is an abnormal 


disconnect. Simply close the session. Some clients record the event to 
phone home later. 


Maintaining a Heartbeat 


Updating QC 


The typical heartbeat sequence is as follows: 


1. TIH sends heartbeat to FLAP clients every 2 minutes if the client is idle 
for more than 2 minutes. This is to get rid of half-closed TCP 
connections which host does not notice until something is queued up in 
the pipe. The heartbeat is a fP token with some data. Client should 
simply reflect the whole thing back. 


2. Client can also send ping to host with FP. TIH simply returns the whole 
packet back. But this is not recommended because client-ping is not 
configurable and it may overload the network. If you have to do it, 
make sure its interval is long enough (several minutes). 


TIH is the official keeper of QC. If another server needs to update QC, it 
can do so by sending MSG__UPDATE_CONTEXT to the user's QID. 
Upon receiving the message, TIH will update it’s QC with the information 
in the QC attached in the QMI message and notify BERP and Tunnel about 
the QC changes. 


The message body should contain 1 byte as UPDATE_CODE. This code 
tells TIH which field should be updated. 


NOTE: Refrain from using CONTEXT_UPDATE__ALL, which 
overwrites entire QC in TIH because this might overwrite changes made by 
other servers. 
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Sending Stats Record with TIH 


The unix_stats server which collects stats from TIH and keeps them on 
hard disk. TIH sends various information (for example, connection, 
plusgroup, and toolbar tracking) to unix_stats. To reduce the number of 
messages, TIH queues up stats in a 2K buffer. It flushes the buffer when it 
is full or when it has been 6 hours since the last flush. 


If another server wants to send records to stats server, it can do so by 
sending MSG__STATS_V2 to TIH. TIH will queue the records in the 
buffer. 


Kicking User Off with XS Token 


If another server want to kick off a user session, it can do so by sending the 
XS token (ASCII text) or Xs token (localized text) to the user's QID. Upon 
receiving XS, TIH sets up a timer and waits for the client to close the 
connection gracefully. The connection is aborted when the timer fires and 
there is no response from client. 


TIH marks all the sessions ended with the XS token and sends that 
information to the stats server. All sessions terminated by XS are 
considered to be normal disconnects. 

If there data is attached to the XS/Xs token, the data will be displayed by 
the client. If a server does not support localized text, it can send commands 


to ctserv and ctserv will in turn send Xs token with localized text. 


SOML has a library called XS_sub to facilitate the use of XS tokens. 


© America Online, Inc. 2001 14 America Online Confidential 


Technical Note: Functionality of the Terminal Handler (TIH), Rel. 1.1 July 2001 


Detailed Event Flow of Member Login 


Figure 3 shows the sequence of events that occurs when a known member 
signs on to the online service: 
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Figure 3: Member Signs On Event Flow 
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Events for Traditional AOL Clients 


The sequence of events for traditional AOL clients is described as follows: 


NOTE: If the member is signing on as a guest account the steps below 
are exactly the same except there is no password reset path. 


1. A member initiates the connection, and the tih process running in the 
comm subsystem accepts the connection. 


2. tih sends a message containing the sign-on notification to the berp for 
routing to login or to sec_login if it is a Gen 4 client that supports 
secure login as described in Step 2a. If the sign-on notification is from 
a Gen 3 or older client, skip to Step 3. 


a. If itis a Gen 4 (secure login) notification, there are approximately 
eight messages in a pre-master secure data protocol that are sent 
back and forth between the client and sec_login to validate a RSA 
security key. (RSA is a government-defined algorithm for a public- 
key cryptography standard.) The berp routes these security data 
messages between the appropriate tih and sec_login processes. 
When a secure link is established, the client sends the sign-on 
notification (Dd token) to sec_login through the berp. 


b. sec_login sends the sign-on notification (Dd token) to the berp for 
routing to login. 


3. The berp routes the sign-on notification (Dd token) to login. 

4. With the account number or screen name and password from the 
member in the sign-on message, login checks the account number and 
password in master_acct.db for validity. Access to master_acct.db 


(Master File) is through the login_switcher and login_worker. 


5. Master File data is retrieved from login_worker and sent back through 
login_switcher to login. 


a. If user has a cancel code or block login code on their master 
account, the message goes to the CIBS router. 


b. If the user mistypes the password twice, the message goes to the 
password reset server. 


6. login then sends a sign-on (test_and_set) request to the berp, which 
routes it to FOLDR. 
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10. 


11. 


12. 


13; 


14. 
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FOLDR checks to see if the member is already signed on and returns 
the results to the berp, which routes it to login. 


Note: If FOLDR senses that the member might already be signed on, 
additional verification procedures are required. For more information, 
see "Dynamics of the login Process" on page 13. 


The last_logout_time is added to the q_context when the test/set 
message for popups is replied to. The q_context is a container for 
information about a member such as the member's account type 
(internal, overhead, or normal), the screen name being used, and the 
client software version. 


last_logout_time has two versions, one for a particular screen name 
and another for the master account's last logout. 


If the member is already signed on, login terminates the sign-on 
activity and sends an XS token with the You are already signed 
on using screen name xyz message to the berp for routing to the 
appropriate tih connected to the client. This condition terminates the 
login sequences. 


The You are already signed on using screen name xyz 
message appears on the member's screen. 


If the member has a SecurID key, login sends a request to theberp. 


If the member is not already signed on, is not a security key holderand 
the client application does not need to be updated, login sends the 
accepted login request to the berp, which routes it to popup. 


If the client application needs to be updated, login sends an update disk 
operation (UDO) request to the berp. For more information about the 
UDO sequence, see the "Client Software Requests Update" section on 
page 28. 


popup sends any promotional pre-welcome forms that are available to 
the client for display. When the pre-welcome activity is complete or not 
required, popup forwards the accepted login request to the berp, 
which routes it to welcome for clients below 5.0 and to Pageman for 
clients above 5.0. 


welcome or pageman sends the Welcome form to the berp, which 
routes it to theappropriate tih. 


tih then sends the Welcome form to the client computer for display. 
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The Welcome form appears on the member's screen. 


Events for SNAC-based Clients/Proxies 


For SNAC-based clients, the login data flow is similar to the above 
description except for the following differences: 


e SNAC messages are used for Login, so the client sends a SX token, 
instead of a Dd token to login. 


¢ Some SNAC clients may also use sec_login. They will use the same 
tokens (Wh, Wd) except the Wd will carry encrypted SNACs. 


¢ SNACs do not support UDO (step 11) and Popup (step 12). 


¢ The Welcome screen is also disabled for SNAC based client because 
the screen is a FDO form. (step 13,14). 
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